feat: add markdown output support for package pages by BYK · Pull Request #151 · npmx-dev/npmx.dev

BYK · 2026-01-27T00:39:33Z

Summary

Add support for getting package information in Markdown format, useful for AI/LLM consumption and command-line tools.

Access Methods

URL suffix: /<package>.md (e.g., /vue.md, /@nuxt/kit.md)
Accept header: Accept: text/markdown

Output Includes

Package metadata (name, version, license, last updated)
Stats table with weekly downloads (with sparkline trend) and dependency count
Install command
Links (npm, repository, homepage, issues)
Keywords and maintainers
Full README content

Security Hardening

URL validation for homepage/bugs links (prevents javascript: protocol injection)
README size limit (500KB) to prevent resource exhaustion
Path exclusion alignment between Vercel rewrites and middleware

vercel · 2026-01-27T00:39:38Z

@BYK is attempting to deploy a commit to the danielroe Team on Vercel.

A member of the Team first needs to authorize it.

vercel · 2026-01-27T21:15:24Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs.npmx.dev	Ready	Preview, Comment	Mar 13, 2026 6:52pm
npmx.dev	Ready	Preview, Comment	Mar 13, 2026 6:52pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
npmx-lunaria	Ignored		Mar 13, 2026 6:52pm

server/utils/markdown.ts

danielroe · 2026-01-28T17:28:41Z

ultimately it might make sense to share some logic with the client (see #169) so we can click 'copy as markdown'

...although that button could also fetch the markdown from the server endpoint, which might be better from a JS bundle size

so... just linking so you're aware

BYK · 2026-01-30T12:27:22Z

@atinux @okineadev are you waiting on me for something? (just making sure I'm not the blocker here)

atinux · 2026-01-30T17:12:04Z

Sorry I was quite busy.

I suggest to not use a middleware here but instead having a server route with /raw prefix similar to how we have here: https://github.com/unjs/undocs/blob/main/app/server/routes/raw/%5B...slug%5D.md.get.ts

Then like on https://github.com/unjs/undocs/blob/main/app/modules/md-rewrite.ts, we can add the rewrite in the generated vercel.json to it happens at the CDN level

Would you be up to update your PR with this approach @BYK ?

Add support for getting package information in Markdown format via: - URL suffix: /package-name.md - Accept header: text/markdown Includes security hardening: - URL validation for homepage/bugs links (prevents javascript: injection) - README size limit (500KB) to prevent DoS - Path exclusion alignment between Vercel rewrites and middleware

@atinux

Address review feedback from @atinux: - Replace middleware with server route at /raw/[...slug].md - Update vercel.json rewrites to point to /raw/:path.md - Add curl user-agent rewrite support for CLI tools - Enable CDN-level caching for markdown responses Also fix maintainer URLs to use npmx.dev instead of npmjs.com

BYK · 2026-01-31T02:41:08Z

@atinux no worries. Updated :)

codecov · 2026-02-04T16:23:09Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

coderabbitai · 2026-02-04T16:30:25Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds server-side support to serve package information as Markdown via a new /raw/** route and a server route handler that parses slugs, resolves package and version data, fetches README with a jsDelivr fallback, obtains weekly and 12‑week download stats and repository info, and returns generated Markdown with Content-Type text/markdown and ISR-aligned caching (60s). Adds server-side markdown generation utilities (sparkline, formatting, URL normalisation, README handling), an ISR route rule for /raw/** in nuxt.config, a markdown alternate link on the package page, Vercel rewrites for markdown/curl requests, unit tests for markdown utilities, and a codecov ignore update.

Suggested reviewers

danielroe
ghostdevv

🚥 Pre-merge checks | ✅ 1

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description check	✅ Passed	The pull request description clearly describes the changeset: adding Markdown format support for package information with specific access methods, output content, and security hardening measures.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

Tip

Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs).
Share your feedback on Discord.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 3

🧹 Nitpick comments (3)

server/routes/raw/[...slug].md.get.ts (1)

130-235: Consider splitting the handler into smaller helpers.

This handler is well over the 50-line guideline; extracting readme, downloads, and version resolution into helpers would improve readability and testability.

As per coding guidelines: Keep functions focused and manageable (generally under 50 lines).
server/utils/markdown.ts (2)
8-27: Guard the sparkline index access.

Clamping or fallbacking the array access keeps the indexing explicitly safe.
🛠️ Safer index access
-      const index = Math.round(normalized * (SPARKLINE_CHARS.length - 1))
-      return SPARKLINE_CHARS[index]
+      const index = Math.round(normalized * (SPARKLINE_CHARS.length - 1))
+      return SPARKLINE_CHARS[index] ?? SPARKLINE_CHARS[SPARKLINE_CHARS.length - 1]
As per coding guidelines: Ensure you write strictly type-safe code, for example by ensuring you always check when accessing an array value by index.

115-279: Consider extracting sections to reduce function length.

generatePackageMarkdown is very long; splitting into section builders (stats, links, readme) would improve readability and maintenance.

As per coding guidelines: Keep functions focused and manageable (generally under 50 lines).

server/routes/raw/[...slug].md.get.ts

server/utils/markdown.ts

BYK · 2026-02-04T21:03:54Z

@atinux ready for another look?

vercel.json

server/utils/markdown.ts

ghostdevv · 2026-02-06T22:51:57Z

ah! we do now have a copy as markdown button on the frontend #1020 - if you rebase you could make any change you need to use your new logic? It would be nice if that button also fetched it dynamically

server/utils/markdown.ts

Co-authored-by: Okinea Dev <hi@okinea.dev>

okineadev · 2026-02-12T08:15:03Z

I think we should also take a look at #1382
It would be nice to somehow integrate the agent instruction fetching functionality as well

# Conflicts: # app/pages/package/[...package].vue # nuxt.config.ts

…supplied maintainer fields - Add vercel.json rewrites for /package/:path to strip prefix and serve markdown - Escape maintainer name with escapeMarkdown() since it's user-supplied - URL-encode maintainer username in link hrefs for safety

BYK · 2026-03-06T18:03:42Z

Thanks for the pointer to #1382! That PR adds llms.txt/llms_full.txt support with agent instruction file fetching (CLAUDE.md, .cursorrules, etc.) — it's a substantial feature with its own middleware, types, and test suite.

I think it makes sense to keep these as separate PRs that can be coordinated:

This PR (feat: add markdown output support for package pages #151): Markdown output via /raw/ routes + content negotiation (curl/Accept header)
PR feat(ui): add llms.txt generation for npm packages #1382: llms.txt standard routes with agent instruction files

They share some underlying infrastructure (markdown generation, package metadata), so once both land, there could be follow-up work to consolidate shared utilities. But merging them now would significantly expand scope.

BYK · 2026-03-06T18:06:28Z

@okineadev @ghostdevv sorry for the long delay. Should be good to go now?

okineadev · 2026-03-06T19:57:01Z

@okineadev @ghostdevv sorry for the long delay. Should be good to go now?

Personally, I abstain from voting.

BYK · 2026-03-09T12:53:22Z

@okineadev who can vote so we can avoid bitrot? :)

BYK marked this pull request as ready for review January 27, 2026 00:41

danielroe requested a review from atinux January 27, 2026 00:51

danielroe mentioned this pull request Jan 27, 2026

feat: Add "Copy for AI" button to package page #169

Draft

7 tasks

vercel bot deployed to Preview – npmx.dev January 27, 2026 21:16 View deployment

okineadev suggested changes Jan 28, 2026

View reviewed changes

server/utils/markdown.ts Outdated Show resolved Hide resolved

server/utils/markdown.ts Show resolved Hide resolved

server/utils/markdown.ts Show resolved Hide resolved

vercel bot had a problem deploying to Preview – docs.npmx.dev January 28, 2026 09:16 Failure

vercel bot deployed to Preview – npmx.dev January 28, 2026 09:17 View deployment

vercel bot deployed to Preview – npmx.dev January 30, 2026 10:15 View deployment

vercel bot deployed to Preview – docs.npmx.dev January 30, 2026 10:15 View deployment

BYK added 3 commits January 31, 2026 02:04

fix: resolve TypeScript errors in markdown utilities

c975020

BYK force-pushed the byk/feat/md branch from 14fe165 to 91a16ee Compare January 31, 2026 02:20

vercel bot deployed to Preview – npmx.dev January 31, 2026 02:22 View deployment

JReinhold mentioned this pull request Feb 2, 2026

feat: Support Accept: text/markdown header for improved LLM usage #725

Open

chore: merge main and resolve vercel.json conflict

2ef5522

vercel bot deployed to Preview – docs.npmx.dev February 2, 2026 10:21 View deployment

vercel bot deployed to Preview – npmx.dev February 2, 2026 10:23 View deployment

chore: merge main and resolve conflicts

d853437

vercel bot had a problem deploying to Preview – docs.npmx.dev February 4, 2026 16:21 Failure

vercel bot deployed to Preview – npmx.dev February 4, 2026 16:22 View deployment

coderabbitai bot reviewed Feb 4, 2026

View reviewed changes

server/routes/raw/[...slug].md.get.ts Outdated Show resolved Hide resolved

server/utils/markdown.ts Show resolved Hide resolved

server/utils/markdown.ts Show resolved Hide resolved

vercel bot deployed to Preview – npmx.dev February 4, 2026 19:53 View deployment

fix: remove repoInfo from route handler after removing from interface

e1f001c

vercel bot deployed to Preview – npmx.dev February 4, 2026 21:02 View deployment

okineadev suggested changes Feb 5, 2026

View reviewed changes

vercel.json Show resolved Hide resolved

server/utils/markdown.ts Outdated Show resolved Hide resolved

ghostdevv requested changes Feb 6, 2026

View reviewed changes

server/utils/markdown.ts Outdated Show resolved Hide resolved

Update server/utils/markdown.ts

c5cf366

Co-authored-by: Okinea Dev <hi@okinea.dev>

vercel bot deployed to Preview – npmx.dev February 9, 2026 17:13 View deployment

lukeocodes mentioned this pull request Feb 13, 2026

feat(ui): add llms.txt generation for npm packages #1382

Open

8 tasks

BYK added 2 commits March 6, 2026 17:34

Merge remote-tracking branch 'origin/main' into byk/feat/md

eebaa28

# Conflicts: # app/pages/package/[...package].vue # nuxt.config.ts

Merge remote-tracking branch 'fork/byk/feat/md' into byk/feat/md

07b045a

vercel bot deployed to Preview – npmx.dev March 6, 2026 17:46 View deployment

vercel bot deployed to Preview – npmx.dev March 6, 2026 18:01 View deployment

Merge branch 'main' into byk/feat/md

e5dc695

BYK requested review from ghostdevv and okineadev March 6, 2026 18:04

vercel bot deployed to Preview – npmx.dev March 6, 2026 18:06 View deployment

Merge branch 'main' into byk/feat/md

87226fa

vercel bot deployed to Preview – docs.npmx.dev March 9, 2026 12:55 View deployment

vercel bot deployed to Preview – npmx.dev March 9, 2026 12:55 View deployment

Merge branch 'main' into byk/feat/md

ae9b240

vercel bot deployed to Preview – docs.npmx.dev March 13, 2026 18:52 View deployment

vercel bot deployed to Preview – npmx.dev March 13, 2026 18:52 View deployment

Uh oh!

Conversation

BYK commented Jan 27, 2026

Summary

Access Methods

Output Includes

Security Hardening

Uh oh!

vercel bot commented Jan 27, 2026

Uh oh!

vercel bot commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

danielroe commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BYK commented Jan 30, 2026

Uh oh!

atinux commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BYK commented Jan 31, 2026

Uh oh!

codecov bot commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

coderabbitai bot commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Suggested reviewers

Review ran into problems

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BYK commented Feb 4, 2026

Uh oh!

Uh oh!

Uh oh!

ghostdevv commented Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

okineadev commented Feb 12, 2026

Uh oh!

BYK commented Mar 6, 2026

Uh oh!

BYK commented Mar 6, 2026

Uh oh!

okineadev commented Mar 6, 2026

Uh oh!

BYK commented Mar 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

vercel bot commented Jan 27, 2026 •

edited

Loading

danielroe commented Jan 28, 2026 •

edited

Loading

atinux commented Jan 30, 2026 •

edited

Loading

codecov bot commented Feb 4, 2026 •

edited

Loading

coderabbitai bot commented Feb 4, 2026 •

edited

Loading

ghostdevv commented Feb 6, 2026 •

edited

Loading